<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Developing CML/Golem dictionaries &mdash; Golem v1.0 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '',
          VERSION:     '1.0',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: ''
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/interface.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="contents" title="Global table of contents" href="contents.html" />
    <link rel="index" title="Global index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="Golem v1.0 documentation" href="index.html" />
    <link rel="next" title="CML/Golem dictionary syntax" href="dictionarysyntax.html" />
    <link rel="prev" title="Summon" href="summon.html" />
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="dictionarysyntax.html" title="CML/Golem dictionary syntax"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="summon.html" title="Summon"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  
  <div class="section" id="developing-cml-golem-dictionaries">
<h1 id="developing-cml-golem-dictionaries">Developing CML/Golem dictionaries<a class="headerlink" href="#developing-cml-golem-dictionaries" title="Permalink to this headline">¶</a></h1>
<div class="section" id="adding-cml-markup-to-your-code">
<span id="cmlmarkup"></span><h2 id="adding-cml-markup-to-your-code"><span id="cmlmarkup"></span>Adding CML markup to your code<a class="headerlink" href="#adding-cml-markup-to-your-code" title="Permalink to this headline">¶</a></h2>
<p>The best way to add CML output to your Fortran program is to use the FoX
library. Documentation on the is beyond the scope of this document, but can be
found on the CMLComp.org wiki and FoX website - here&#8217;s a <a class="reference external" href="http://www.uszla.me.uk/FoX/WCML_tutorial.html">tutorial on how to
mark up a code using FoX and WCML</a>.</p>
<ul class="simple">
<li><a class="reference external" href="http://www.cmlcomp.org">CMLcomp.org</a></li>
<li><a class="reference external" href="http://www.uszla.me.uk/FoX/">FoX, the Fortran XML Library</a></li>
</ul>
<p>We will assume your code was marked up using this, or (in general) that the
format you have used for the following tags is, broadly speaking, similar to
that used by FoX&#8217;s WCML library.</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">&lt;parameter&gt;</span></tt> and <tt class="docutils literal"><span class="pre">&lt;parameterList&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;property&gt;</span></tt> and <tt class="docutils literal"><span class="pre">&lt;propertyList&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;atomArray&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;scalar&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;metadata&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;matrix&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;lattice&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;cellParameter&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;array&gt;</span></tt></li>
</ul>
<p>If you&#8217;re using FoX, this is already true; if you&#8217;re not, for more details of
how we recommend you use these CML elements, see the CMLComp website at
<a class="reference external" href="http://cmlcomp.org/">http://cmlcomp.org/</a>.</p>
<p><a class="reference external" href="http://www.uszla.me.uk/FoX/DoX/FoX_wcml.html">WCML</a> does contain some
output routines - those relating to <tt class="docutils literal"><span class="pre">&lt;kpoint&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;kpointList&gt;</span></tt> and
<tt class="docutils literal"><span class="pre">&lt;band&gt;</span></tt> in particular - which Golem does not have the means, at present, to
automatically understand. There are efforts to <a class="reference external" href="http://cmlcomp.org/t/wiki/EigenvalueRepresentation">standardise the usage of
these tags</a>, but at
present there is still ongoing discussion about how best to represent these
concepts. It will be possible to add support for these tags later; in the
meantime, later in this manual you will find documentation on how
to extract data from these concepts using XML/XPath methods once you have
located them using Golem.</p>
</div>
<div class="section" id="producing-a-cml-golem-dictionary">
<h2 id="producing-a-cml-golem-dictionary">Producing a CML/Golem dictionary<a class="headerlink" href="#producing-a-cml-golem-dictionary" title="Permalink to this headline">¶</a></h2>
<p>Your Golem distribution ships with a program called <tt class="docutils literal"><span class="pre">make_dictionary</span></tt>. This
scans output files from your code for the above tags, works out where they are
in the file in terms of XPath expressions, and puts in a mechanism for reading
the data found in the file. (In brief: each of the above tags is associated
with an XSLT stylesheet which converts the CML to a <a class="reference external" href="http://json.org/">JSON</a>
object, which is then converted into a Python object by the Golem library.)</p>
<p>This will associate each CML dictionary reference with where it is in the
file, and if it&#8217;s on a value-bearing element - the elements listed above, with
the exception of <tt class="docutils literal"><span class="pre">parameterList</span></tt> and <tt class="docutils literal"><span class="pre">propertyList</span></tt> - will associate the
right stylesheet with it so it can be read.</p>
<p>So, as far as <em>reading</em> the output of your code goes, you can generate your
dictionary automatically, as long as you can generate CML which completely
covers the potential range of output of your code. If you have an automated
test suite, run it and collate the CML output - that makes a very, very good
start. If not, rerunning a large number of simulations which exercise every
part of the codebase is a good idea: this is the approach taken with the
CASTEP dictionary.</p>
<div class="section" id="using-make-dictionary">
<h3 id="using-make-dictionary">Using make_dictionary<a class="headerlink" href="#using-make-dictionary" title="Permalink to this headline">¶</a></h3>
<p>Like the other command-line tools which ship with Golem, <tt class="docutils literal"><span class="pre">make_dictionary</span></tt>
comes with a help message:</p>
<pre>$ make_dictionary --help
usage: make_dictionary options file1.xml [file2.xml ...]

options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -m FILE, --model-dictionary=FILE
                        Model dictionary to incorporate
  -i FILE, --input-config=FILE
                        Input configuration file
  -o FILE, --output=FILE
                        Output filename (defaults to stdout)
  -p PREFIX, --prefix=PREFIX
                        Dictionary prefix
  -n NAMESPACE, --namespace=NAMESPACE
                        Dictionary namespace
  -t TITLE, --title=TITLE
                        Dictionary title
  -l, --use-title       Use titles to distinguish between potential concepts?
  -d, --use-id          Use IDs to distinguish between potential concepts?</pre>
<p>This, admittedly, does look quite intimidating, but let&#8217;s take a concrete
example.</p>
<p>Imagine a new simulation code,  CMLized using the instructions above.</p>
<p>Firstly, one needs to enter the short name - something easy to remember, say
<tt class="docutils literal"><span class="pre">megasim</span></tt> - and the namespace for the dictionary, which was picked when
CMLizing it. Let&#8217;s say that it has been decided that its dictionary namespace
should be <tt class="docutils literal"><span class="pre">http://www.example.com/megasim/dictionary/</span></tt>.</p>
<p>A quick aside on choosing namespaces: this namespace should really be unique
among all CML codes, so make sure to pick a URL in a bit of webspace you
control; there doesn&#8217;t actually <em>have</em> to be anything there if you go there in
a Web browser, though. The actual rules of XML namespaces are very, very
complex, but if you think of it in this context as a unique name identifying
your dictionary, you&#8217;ll be OK.</p>
<p>Let us write the dictionary into a file called <tt class="docutils literal"><span class="pre">megasimDict.xml</span></tt>, with
the title <tt class="docutils literal"><span class="pre">MegaSim</span> <span class="pre">Dictionary</span></tt>, and dictRefs have been added to
every concept you want to read - so we don&#8217;t have to resort to using
<tt class="docutils literal"><span class="pre">title</span></tt> or <tt class="docutils literal"><span class="pre">id</span></tt> to distinguish between the pieces of CML representing
those concepts. The <tt class="docutils literal"><span class="pre">title</span></tt> attribute is designed for people rather than
machines to read: as such, using the value of <tt class="docutils literal"><span class="pre">title</span></tt> to distinguish between
general concepts is something of an abuse of its intended usage. Only one
element with a given <tt class="docutils literal"><span class="pre">id</span></tt> may occur within a document, and as such <tt class="docutils literal"><span class="pre">id</span></tt>
should not be used to identify any concept which could occur more than once in
a document. Thus, for consistency&#8217;s sake, if nothing else, it is better to use
<tt class="docutils literal"><span class="pre">dictRef</span></tt> everywhere. The WCML library enforces this restriction.</p>
<p>Now we collect a set of the CML output from MegaSim - if you have a test
suite, we run the CMLized code over it and collect all the outputs, putting
them in the current working directory. We will assume their filenames all end
in <tt class="docutils literal"><span class="pre">.cml</span></tt>. Once that has been done, the following commandline:</p>
<div class="highlight"><pre><span class="nv">$ </span>make_dictionary -o megasimDict.xml -p megasim
   -n <span class="s2">&quot;http://www.example.com/megasim/dictionary&quot;</span>
   -t <span class="s2">&quot;MegaSim Dictionary&quot;</span> *.cml
</pre></div>
<p>will build you a CML/Golem dictionary. It&#8217;ll walk over the supplied CML files,
identify what, where and how each <tt class="docutils literal"><span class="pre">dictRef</span></tt> is used, and write the resulting
dictionary to <tt class="docutils literal"><span class="pre">megasimDict.xml</span></tt>.</p>
</div>
<div class="section" id="trying-it-for-yourself">
<h3 id="trying-it-for-yourself">Trying it for yourself<a class="headerlink" href="#trying-it-for-yourself" title="Permalink to this headline">¶</a></h3>
<p>If you&#8217;ve downloaded the Golem source distribution, change directory into the
directory where you&#8217;ve unzipped it; it has a subdirectory
<tt class="docutils literal"><span class="pre">docs/examples/rmcprofile</span></tt>. Change into that directory, and run the
following:</p>
<div class="highlight"><pre><span class="nv">$ </span>make_dictionary -o rmcprofileDict.xml -p rmcprofile
    -n <span class="s2">&quot;http://www.esc.cam.ac.uk/rmcprofile&quot;</span>
    -t <span class="s2">&quot;rmcprofile dictionary&quot;</span> ag3cocn6_300k.xml
</pre></div>
<p>This will write a dictionary, <tt class="docutils literal"><span class="pre">rmcprofileDict.xml</span></tt>, in that directory: take
a look at it (and <tt class="docutils literal"><span class="pre">ag3cocn6_300k.xml</span></tt>) to see how <tt class="docutils literal"><span class="pre">dictRef``s</span> <span class="pre">in</span> <span class="pre">the</span> <span class="pre">CML</span>
<span class="pre">get</span> <span class="pre">turned</span> <span class="pre">into</span> <span class="pre">``&lt;entry&gt;</span></tt> elements in the dictionary.</p>
</div>
<div class="section" id="improving-the-dictionary">
<h3 id="improving-the-dictionary">Improving the dictionary<a class="headerlink" href="#improving-the-dictionary" title="Permalink to this headline">¶</a></h3>
<p>From here, there are four major things you can do to improve the dictionary;</p>
<ul class="simple">
<li>add definitions and descriptions to document the terms in the dictionary</li>
<li>add further information to annotate the types of data a term can return</li>
<li>add stylesheets to the dictionary to (for example) produce code input</li>
<li>add information on the relationships between concepts</li>
</ul>
<p>Each of these is out of bounds here (and is covered in the next section), but
if you have a dictionary to which these have been added, and you wish to
recompile the dictionary you can copy this information across into your new
dictionary by using your old dictionary as a model. Pass it to
<tt class="docutils literal"><span class="pre">make_dictionary</span></tt> with the <tt class="docutils literal"><span class="pre">-m</span></tt> flag:</p>
<div class="highlight"><pre><span class="nv">$ </span>make_dictionary -m old_dictionary.xml -o new_dictionary.xml <span class="o">[</span>...<span class="o">]</span> *.cml
</pre></div>
<p>If a term occurs in both dictionaries, any definitions, descriptions, or
<tt class="docutils literal"><span class="pre">&lt;golem:possibleValues&gt;</span></tt> defined in the model dictionary are merged into
the new one. This is particularly useful if you change the document structure
of the CML you output, but you don&#8217;t want to lose the extra information you&#8217;ve
added to your old dictionary.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3>Table Of Contents</h3>
            <ul>
<li><a class="reference external" href="">Developing CML/Golem dictionaries</a><ul>
<li><a class="reference external" href="#adding-cml-markup-to-your-code">Adding CML markup to your code</a></li>
<li><a class="reference external" href="#producing-a-cml-golem-dictionary">Producing a CML/Golem dictionary</a><ul>
<li><a class="reference external" href="#using-make-dictionary">Using make_dictionary</a></li>
<li><a class="reference external" href="#trying-it-for-yourself">Trying it for yourself</a></li>
<li><a class="reference external" href="#improving-the-dictionary">Improving the dictionary</a></li>
</ul>
</li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="summon.html" title="previous chapter">Summon</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="dictionarysyntax.html" title="next chapter">CML/Golem dictionary syntax</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/makingdictionaries.txt">Show Source</a></li>
            </ul>
            <h3>Quick search</h3>
            <form class="search" action="search.html" method="get">
              <input type="text" name="q" size="18" /> <input type="submit" value="Go" />
              <input type="hidden" name="check_keywords" value="yes" />
              <input type="hidden" name="area" value="default" />
            </form>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="dictionarysyntax.html" title="CML/Golem dictionary syntax"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="summon.html" title="Summon"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2008, Andrew Walkingshaw.
      Last updated on Oct 01, 2008.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
    </div>
  </body>
</html>